home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / formats / iff / newiff.lzh / NewIFF / IFFP_Modules.README < prev    next >
Text File  |  1992-06-14  |  9KB  |  213 lines
  1.  
  2.             IFFP Modules - April 1992
  3.                    version 37.9
  4.  
  5. Special notes regarding the 37.9 release:
  6.  
  7.     - All examples and modules which use Intuition #defines
  8.       have been modified to force the use of (and use) the
  9.       new prefixed Intuition labels for these #defines.
  10.  
  11.     - ilbmw.c was modified to deal with source bitmaps which
  12.       have larger bytes-per-row than normal.
  13.  
  14. Special notes regarding the previous 37.8 release:
  15.  
  16.     - the screen.c module now checks to see if the opened
  17.       screen is a public screen, and if so, sets the screen's
  18.       status to public before opening a window on it.
  19.  
  20.     - the screen and display closing routines now return
  21.       success or failure so that public screen openers
  22.       can check to make sure that they were able to
  23.       close their display.
  24.  
  25.     - all iffp module strings and message routines have
  26.       now been centralized in a new module iffpstrings.c.
  27.       This will facilitate internationalization.
  28.  
  29. These iffparse.library code modules and examples are designed as
  30. replacements for the original EA IFF code.  In some modules, it has
  31. been possible to retain much of the original code.  However, most
  32. structures and most higher level function interfaces have changed.
  33.  
  34. On the plus side, these new modules contain many new high-level
  35. easy-to-use functions for querying, loading, displaying, and saving
  36. ILBMs.  During their development, modules similar to these have been
  37. used inhouse at Commodore for the 2.0 Display program and several other
  38. ILBM applications.  The screen.c module provides powerful display-opening
  39. functions which are 1.3-compatible yet provide a host of new options under
  40. 2.0 such as centered overscan screens, full-video display clips, border
  41. transparency control, and autoscroll.  New modules have been added for
  42. printing (screendump) and for preserving/adding chunks (copychunks).
  43. And the 8SVX example now actually plays samples and instruments.
  44. In addition, clipboard support is automatic for all applications that
  45. use the IFFP modules because parse.c's openifile() interprets the
  46. filename -c[n] (ie. "-c", "-c1", "-c2", etc.) as clipboard unit n.
  47.  
  48.  
  49. All of the applications presented here require iffparse.library which
  50. is distributed on Workbench 2.0.  Please note that iffparse.library is
  51. a 1.3-compatible library, and that all of these modules and examples
  52. have been designed to take advantage of 2.0, but also work under 1.3.
  53. Developers who wish to distribute iffparse.library on their commercial
  54. products may execute a 2.0 Workbench license, or may get an addendum to
  55. their 1.3 Workbench license to allow distribution of iffparse.library.
  56.  
  57.  
  58. It was not necessary to port the gio IO speedup code since iffparse
  59. can use your compiler's own buffered IO routines through the callback
  60. stdio_stream() in parse.c.  Depending on your application, you may want
  61. to add your own additional buffering to this stdio_stream() code.
  62.  
  63.  
  64. Most of the high-level function pairs provided in these modules have
  65. been designed to provide safe cleanup for themselves.  For example,
  66. a loadbrush() that succeeds or fails at any point can be cleaned up
  67. via unloadbrush.  The cleanup routines null out the appropriate
  68. pointers so that allocations will not be freed twice.
  69.  
  70.  
  71. All applications are built upon the parse.c module.  The basic concept
  72. of using the parse.c module are:
  73.  
  74.     - Define tag-like arrays of your desired chunks (readers only)
  75.     - Allocates one or more [form]Info structures as defined in
  76.         iffp/[form]app.h (for example an ILBMInfo defined in
  77.         iffp/ilbmapp.h).
  78.     - Initialize the ParseInfo part of these structures to the desired
  79.         chunk arrays, and to an IFFHandle allocated via iffparse
  80.         AllocIFF().
  81.     - Use the provided high level load/save functions, or use the
  82.         lower level parse.c openifile(), reader-only parseifile()/
  83.         getcontext()/nextcontext(), and closeifile().  The filename
  84.         -c[n] may be used to read/write clipboard unit n.
  85.     - Clean up, FreeIFF(), and deallocate [form]Info's.
  86.  
  87.  
  88. IMPORTANT NOTES - Most of the higher-level load functions keep the
  89.     IFFHandle (file or clipboard) open.  While the handle is
  90.     open, you may use parse.c functions (such as findpropdata)
  91.     OR direct iffparse functions (FindProp(), FindCollection())
  92.     for accessing the gathered chunks.  However, it is not a good
  93.     idea to keep a filehandle OR the clipboard open.  While
  94.     a clipboard unit is open, no other applications can clip
  95.     to the unit.  And while a file is open, you can't write the
  96.     file back out.  So, instead of keeping the file or unit
  97.     open, you can use copychunks (in copychunks.c) to create
  98.     a copy of your gathered chunks, and do an early closeifile()
  99.     (parse.c).  Then access and later write back out (if you wish)
  100.     and deallocate your copied chunks via the routines in the
  101.     copychunks module (findchunk, writechunklist, freechunklist).
  102.  
  103. WARNING REGARDING COMPLEX FORMS    
  104.         Regarding Complex FORMs - The parse.c module will enter complex
  105.     formats such as CATSs, LISTs, and nested FORMs to find the FORM
  106.     that you are interested in.  This is great.  However, if you are
  107.         a read-modify-write program, you should warn your user when this
  108.         occurs unless YOU are capable of recreating the complex format.
  109.     Otherwise, your user may unknowingly destroy his complex file
  110.     by writing over it with your program.  Example - a paint
  111.     program could read an ILBM out of a complex LIST containing
  112.     pictures and music, and then save it back out as a simple ILBM,
  113.     causing the user to lose his music and other pictures.
  114.     To determine if a complex form was entered after a load,
  115.     check the (form)Info.ParseInfo.hunt field.  If TRUE (non-zero), 
  116.     then your file was found inside a complex format.
  117.  
  118. COMPILATION NOTES
  119.     These modules and examples have been compiled using SAS C 5.10a
  120.     and Manx C 5.0d, with 2.0 (37.1) include files and 2.0 amiga.lib.
  121.     You must have at least 37.1 alib_protos.h (older versions of
  122.     this include file contained the amiga.lib stdio protos also
  123.     which conflict with both SAS and Manx stdio).  For Manx, I
  124.     also had to comment out the conditional definition of abs() in
  125.     libraries/mathffp.h.  These modules do not use mathffp, but
  126.     the mathffp include file is pulled in by alib_protos.h.
  127.     When compiling with Manx, a warning seems to be generated for
  128.     each string constant assigned to a UBYTE * field, and also
  129.     by some references to ilbm->colortable.
  130.  
  131.  
  132.         LIST OF IFFP MODULES AND APPLICATIONS
  133.                 =====================================
  134.     NOTE - Some useful functions are listed with each module
  135.         See module source code for docs on each function.
  136.  
  137.  
  138. APPLICATIONS (these require linkage with modules - see Makefiles)
  139. ============
  140. ILBMDemo    Displays an ILBM, loads a brush, saves an ILBM, opt. print
  141. ILBMLoad    Queries an ILBM and loads it into an existing screen
  142. ILBMtoC        Outputs an ILBM as C source code
  143. ILBMtoRaw    Converts an ILBM to raw plane/color file
  144. RawtoILBM    Converts raw plane/color file (from ILBMtoRaw) to an ILBM
  145. 24bitDemo    Saves a simple 24-bit ILBM and then shows it 4 planes at
  146.         a time (if given filename, just does the show part)
  147. Play8SVX    Reads and plays an 8SVX sound effect or instrument
  148.           - LoadSample, UnloadSample, PlaySample, OpenAudio,
  149.             CloseAudio, and body load/unpack functions
  150. ScreenSave    Save the front screen as an ILBM, with an icon
  151.  
  152.  
  153. OTHER EXAMPLES (use iffparse.library directly and require no modules)
  154. ==============
  155. Sift        Checks and prints outline of any IFF file (uses RAWSTEP)
  156. ILBMScan    Prints out useful info about any ILBM
  157. ClipFTXT    Demonstrates simply clipping of FTXT to/from clipboard
  158. apack.asm    Dr. Gerald Hull's assembler replacement for packer.c
  159.  
  160.  
  161. GENERAL IFFPARSE SUPPORT MODULE
  162. ===============================
  163. parse.c        File/clipboard IO and general parsing
  164.           - openifile, closeifile, parseifile, getcontext,
  165.             nextcontext, contextis, currentchunkis, PutCk chunk
  166.             writing function, and IFFerr text error routine
  167.  
  168. iffpstrings.c   Centralized string and message handling for modules.
  169.  
  170. ILBM READ MODULES
  171. =================
  172. loadilbm.c    High level ILBM load routines which are passed filenames
  173.         (calls getbitmap)
  174.           - loadbrush/unloadbrush, loadilbm/unloadilbm, and queryilbm
  175. getbitmap.c    brush/bitmap loading (non-display, calls ilbmr.c)
  176.           - createbrush/deletebrush, getbitmap/freebitmap
  177. getdisplay.c    bitmap load/display (calls screen.c, ilbmr.c)
  178.           - showilbm/unshowilbm, createdisplay/deletedisplay
  179. screen.c    1.3/2.0 ECS/non-ECS compatible screen/window module
  180.           - opendisplay, openidscreen, modefallback, clipit
  181. ilbmr.c        Lower level ILBM body/color load routines (calls unpacker.c)
  182.           - loadbody, loadcmap, getcolors/freecolors,
  183.             alloccolortable, getcamg (gets or creates modeid)
  184. unpacker.c    BODY unpacker
  185.  
  186.  
  187. ILBM WRITE MODULES
  188. ==================
  189. saveilbm.c    High level ILBM saving routines which are passed filenames
  190.         (calls ilbmw.c)
  191.           - screensave and saveilbm
  192. ilbmw.c        Lower level ILBM body/color save routines (calls packer.c)
  193.           - InitBMHD, PutCMAP, PutBODY
  194. packer.c    BODY packer
  195.  
  196.  
  197. EXTRA MODULES
  198. =============
  199. copychunks.c    Chunk cloning and chunk list writing routines
  200.           - copychunks, findchunk, writechunklist, freechunklist
  201. screendump.c    Screen printing module (iffparse not required)
  202. bmprintc.c    Module to output ILBM as C code
  203.  
  204.  
  205. INCLUDE FILES
  206. =============
  207. iffp/#?.h    This subdirectory may be kept in your current directory
  208.         or in your main include directory.
  209.  
  210.  
  211. Thanks to Steve Walton for his code changes for Manx/SAS compatibility,
  212. and to Bill Barton and John Bittner for their comments and suggestions.
  213.